Application Interface

Modified on 2010/12/10 18:42 by John Categorized as Uncategorized
===Overview===
The application interface has been designed to allow Jetfire objects to be accessed directly within .net code.  Jetfire objects can be accessed a)using Jetfire framework classes b)using .net DLR interface or c) a combination of the two techniques.

Jetfire programs can also [Using dot net Objects|access .net objects].

Exceptions can be thrown in Jetfire and caught directly in .net code.
{TOC}

=== Calling Jetfire Directly using .net DLR ===
Jetfire methods and properties can be called just like any other C# method or property using .net DLR.   This requires C# the 'dynamic' keyword be employed (a .net rel 4 feature).

====DLR Example====
Here is a simple Jetfire program.

@@namespace DlrExample 
{ 
    public workflow MyFlow 
    { 
        public string MyString{get; set;} 
        public string MyAction(){ return this.MyString;} 
        public string MyAction(string s){return s;} 
    } 
}@@

To work with Jetfire objects the following C# code can be used.

@@dynamic myFlow = nexus.New<Workflow>("DlrExample.MyFlow"); 
// 
// Access the Workflow's properties and methods 
// 
myFlow.MyString = "some string"; 
Assert.AreEqual("some string", (string)myFlow.MyString); 
Assert.AreEqual("some string", (string)myFlow.MyAction()); 
Assert.AreEqual("some other string", (string)myFlow.MyAction("some other string"));@@

For more details see the blog articles:
[http://yourdotnetdesignteam.blogspot.com/2010/06/jetfire-objects-now-support-net-dlr.html|Using .net DLR with Jetfire].

=== Calling Jetfire Directly using Classes ===
There are 3 major classes
*TjNexus : Represents the [client nexus] cache for a particular user.   This class is instantiated when a user logs in.  
*TjWorkflow : This is the basic building block within Jetfire giving programmatic access to the [workflow|workflow object]. Most Jetfire objects inherit from the TjWorkflow class.
*TjCompositeClass : Represents the code or the operations for jetfire objects.

The TjWorkflowClass (and TjWorkflow) support being called directly from .net using the "Get", "Set" or "Execute" methods.  New TjWorkflow objects can be created by using the "New" method on TjWorkflowClass.

====Set Method====
The 'Set' method is supported by the .net classes TjWorkflow and TjWorkflowClass.  This method support setting the value of a single property or multiple properties.   The access modifier for the property must be public in order to set the value.  Fields can not be set.
====Get Method====
The 'Get' method is supported on TjWorkflow and TjWorkflowClass.  This method support getting a single value of a property, multiple property values, or field.   The access modifier for the property must be public in order to get the value.  A value of a field will be retrived regardless of its access modifier.

The following C# code illustrates how to 'Get' the value of Jetfire property.   This code is part of the [http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Simple%20Storage%20Code%20Example|'Hello World' example].
@@
  // Get the value from the property named "Hello". 
  string creationTime = workflow.Get<string>("Hello"); 
@@

When dealing with a Jetfire list or array object the 'Get' method will automatically convert to an array.  This code is part of
[http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Department%20Request%20Approval%20Example&referringTitle=C-Sharp%20Examples|'Departmental Approval Request' example].
@@
  // Get the roles of the logged in user.
  TjRole[] roles = nexus.UserLogin.DefaultProfile.Get<TjRole[]>("roles");
@@

To 'get' multiple property values a list of property names can be specified.  This code is part of
[http://jetfire.codeplex.com/Wiki/View.aspx?title=Getting%20and%20Setting%20Multiple%20Workflow%20Object%20Properties|'Getting and Setting Multiple Properties' example].
@@
  // Get the values of the properties specified.
  TjItemResult[] items = machine.Get(
     new string[] { 
                    "MachineName", 
                    "InstalledDate", 
                    "Location", 
                    "Condition", 
                    "Weight" });
@@


====Execute Method====
The 'Execute' method will execute public instance and static methods.

The following C# code illustrates how to 'Get' the value of Jetfire property.   This is part of the [http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Building%20A%20Simple%20Human%20Interface%20Example&referringTitle=C-Sharp%20Examples|'DVD' example].

@@
  // Execute the 'Borrow' method on the workflow 'dvd'.
  dvd.Execute("Borrow");
@@
====New Method====
The 'New' method, supportted only the TjWorkflowClass, creates a new workflow object.  Workflows created in this manner are automatically made a '[root object]'.

The following C# code illustrates how to 'Get' the value of Jetfire property.   This is part of the [http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Simple%20Storage%20Code%20Example|'Hello World' example].

@@
// Find a workflow class called "HelloWorld" in a namespace called "test".
TjWorkflowClass workflowClass = nexus.FindClass<TjWorkflowClass>("test", "HelloWorld"); 
TjWorkflow workflow = workflowClass.New(); 
@@


Parmeters may also be passed as the following C# code illustrates.

@@
//creates a new object of the type "Role" where the name is "Manager".
TjRole roleManager = nexus.RoleClass.New<TjRole>("Manager");
@@
===Access Modifiers===
In Jetfire methods are equivalent to commands and properties to information.  It is desirable to control when commands are allowed to execute and when information can be viewed or changed. 

To accomplish this Jetfire supports [Dynamic Access Modifier|dynamic access modifiers]. With this construct access modifiers can be dynamic. That is a method's or property's access modifier  (whether it is private or public) can be changed programmatically.

By testing whether a method's access modifier an application can 'grey' out a command when the method is private.  For example in the [http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Building%20A%20Simple%20Human%20Interface%20Example&referringTitle=C-Sharp%20Examples|DVD example], the borrow method can be tested using this C# code construct.

(((
{{
: if(dvd.DynamicAccessModifier("Borrow") == TjAccessModifierType.Private) {br}
: {
:: // take action to 'grey' out 'Borrow' command
: }
}}
)))
===Jetfire Exceptions===
Exceptions can be throw in Jetfire with the 'throw exception()' construct.   There is no need to create a exception object as in .net.  The construct supports 0 to n parameters being passed. The following code is part of [http://jetfire.codeplex.com/Wiki/View.aspx?title=Jetfire%20Exception%20Example&referringTitle=C-Sharp%20Examples|'Throwing Exceptions' example].
(((
{{
: // Jetfire property
: public int Number
:{
:: set
:: {
::: if(value < 0 || value > 10)
::::throw exception("Houston, there is a problem!");
::: this.number = value;
:: }
:}
}}
)))
This exception can be caught directly in C# code.
(((
{{
:try
:{
::flow.Set("Number", 11);
:}
:catch (JetfireException ex)
:{
:: // take some action
:}
}}
)))
===API Examples===
[http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=C-Sharp%20Examples&referringTitle=Home|C# Examples on Code Plex]
Meta Keywords:
Meta Description:
Change Comment: